Add auto-renaming of linked files on entry data change #13295

paudelritij · 2025-06-09T17:14:11Z

This PR introduces an option to automatically rename linked files when the associated entry data is modified. The feature is configurable in Preferences under Linked files -> Linked file name conventions, with a default setting of false. It also includes handling for entries with multiple attached files and adds relevant test cases.

Steps to test

Open JabRef and go to Preferences > Linked files.
Enable [ ] Auto rename files if entry changes.
Create a new entry and attach a file.
Modify any field in the entry.
Check that the linked file's name updates to match the new citation key.
Test with multiple files to ensure all are renamed.

Mandatory checks

I own the copyright of the code submitted and I license it under the MIT license
Change in CHANGELOG.md described in a way that is understandable for the average user (if change is visible to the user)
Tests created for changes (if applicable)
Manually tested changed features in running JabRef (always required)
Screenshots added in PR description (if change is visible to the user)
Checked developer's documentation: Is the information available and up to date? If not, I outlined it in this pull request.
Checked documentation: Is the information available and up to date? If not, I created an issue at https://github.com/JabRef/user-documentation/issues or, even better, I submitted a pull request to the documentation repository.

- Implemented a preference option under Linked files -> Linked file name conventions to enable auto-renaming of files when entry data changes (default: false). - Added functionality to listen for entry change events and rename files if the preference is enabled and the file name matches the defined pattern. - Ensured that no action is taken if the pattern is empty, as the file name would not match. - Considered scenarios where an entry has multiple files attached and handled them appropriately. - Added test cases to verify the new functionality.

jabgui/src/main/java/org/jabref/gui/externalfiles/AutoRenameFileOnEntryChange.java

jabgui/src/main/java/org/jabref/gui/preferences/linkedfiles/LinkedFilesTab.java

jabgui/src/main/java/org/jabref/gui/preferences/linkedfiles/LinkedFilesTabViewModel.java

jabgui/src/test/java/org/jabref/gui/externalfiles/AutoRenameFileOnEntryChangeTest.java

trag-bot · 2025-06-09T17:17:55Z

jablib/src/main/java/org/jabref/logic/FilePreferences.java

@@ -106,6 +109,18 @@ public void setStoreFilesRelativeToBibFile(boolean shouldStoreFilesRelativeToBib
        this.storeFilesRelativeToBibFile.set(shouldStoreFilesRelativeToBibFile);
    }

+    public boolean shouldAutoRenameFilesOnChange() {


The method should return an Optional instead of a primitive boolean to avoid returning null and to align with modern Java practices.

trag-bot · 2025-06-10T00:57:54Z

jabgui/src/main/java/org/jabref/gui/externalfiles/AutoRenameFileOnEntryChange.java

+    }
+
+    private boolean relatesToFilePattern(String fileNamePattern, FieldChangedEvent event) {
+        Set<String> extractedFields = new HashSet<>();


Using 'new HashSet<>()' is not optimal. Consider using 'Set.of()' for better readability and performance as per modern Java practices.

koppor · 2025-07-07T19:22:41Z

Ensure if the target file exists, do not use that name, use FileNameUniqueness.getNonOverWritingFileName(targetDirectory, targetFileName) to ensure that there is a unique other file name.

(Note to us: File should be kept even there are binary equal files. Otherwise, it gets complicated. E.g., if the same file is attached to another entry).

paudelritij · 2025-07-15T06:33:29Z

Ensure if the target file exists, do not use that name, use FileNameUniqueness.getNonOverWritingFileName(targetDirectory, targetFileName) to ensure that there is a unique other file name.

(Note to us: File should be kept even there are binary equal files. Otherwise, it gets complicated. E.g., if the same file is attached to another entry).

I am trying implementing it in org.jabref.logic.externalfiles.LinkedFileHandler#renameToSuggestedName to put uniqueFileName. However, I'm encountering an issue with org.jabref.logic.search.indexing.DocumentReader#addMetaData, which is causing errors when reading timestamps. There may be creation of a loop where file changes name from e.g. abc.pdf to abc(1).pdf to abc.pdf again repeatedly. Any insights on how to resolve this would be greatly appreciated.

" ERROR: Could not read timestamp for /Users//Documents/JabRef/Gen28_ - Hands on Machine Learning with Scikit Learn, Keras, and TensorFlow.pdf: java.nio.file.NoSuchFileException: /Users//Documents/JabRef/Gen28_ - Hands on Machine Learning with Scikit Learn, Keras, and TensorFlow.pdf "

koppor · 2025-07-15T06:46:02Z

@LoayGhreeb Do you have some hints maybe?

LoayGhreeb · 2025-07-16T13:25:37Z

I am trying implementing it in org.jabref.logic.externalfiles.LinkedFileHandler#renameToSuggestedName to put uniqueFileName. However, I'm encountering an issue with org.jabref.logic.search.indexing.DocumentReader#addMetaData, which is causing errors when reading timestamps. There may be creation of a loop where file changes name from e.g. abc.pdf to abc(1).pdf to abc.pdf again repeatedly. Any insights on how to resolve this would be greatly appreciated.

I don't think the problem is with the indexing itself. The NoSuchFileException means it's trying to access a file that doesn't exist, maybe it's still trying to use the old name, or the new one, but since there's a loop renaming the file back and forth, the file might not be available at the expected time during indexing.

I guess this loop could be happening if the same file is linked to two different entries. Could that be the case?

Please try to investigate further by adding some breakpoints to understand why, and where this loop is happening. Also, if possible, please push the commits that reproduce this issue, either here or in a new branch so we can take a proper look and help without guessing what's going on.

…licts

trag-bot · 2025-07-20T09:01:36Z

jabgui/src/test/java/org/jabref/gui/externalfiles/AutoRenameFileOnEntryChangeTest.java

+    @Test
+    void multipleFilesRenameOnEntryChange() throws IOException {
+        // create multiple entries
+        List<String> fileNames = Arrays.asList(


Using Arrays.asList is outdated. Modern Java practices recommend using List.of() for creating immutable lists with fixed elements.

trag-bot · 2025-07-20T09:03:06Z

jablib/src/main/java/org/jabref/logic/util/io/FileNameUniqueness.java

+     * of duplicate markers. For example, if "paper (1).pdf" is already linked to the entry and is the correct format,
+     * the method will return "paper (1).pdf" instead of generating "paper (2).pdf".
+     */
+    public static String generateUniqueFileName(Path targetDirectory, String proposedName, String fileAlreadyInUse) {


Method accepts null parameter 'fileAlreadyInUse' which violates modern Java practices of avoiding null parameters. Should use Optional instead.

trag-bot · 2025-07-20T09:22:46Z

@trag-bot didn't find any issues in the code! ✅✨